home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1992 June: ROMin Holiday / ADC Developer CD (1992-06) (''ROMin Holiday'')_iso / Developer Connection - 06-1992.iso / Development Platforms / Apple II / Essentials / Technical.Notes / IIGS / TN.IIGS.064 < prev    next >
Encoding:
Text File  |  1989-09-03  |  42.4 KB  |  866 lines  |  [TEXT/pdos]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5.  
  6.  
  7. Apple IIGS
  8. #64:    Apple IIGS Installer and Installer Scripts
  9.  
  10. Revised by:    Jim Luther                                      September 1989
  11. Written by:    Jim Luther & "Jay" Schaffer                          July 1989
  12.  
  13. This Technical Note describes how the Apple IIGS Installer program executes 
  14. script files and documents how to write script files for it.  Note that some 
  15. of the information in this Note is specific to Installer V1.10.
  16. Changes since July 1989:  Changed the sourcePrefix and sourcePathname 
  17. field descriptions, since sourcePrefix must not be empty if any sourcePathname 
  18. fields are partial pathnames.
  19. _____________________________________________________________________________
  20.  
  21.  
  22. Introduction
  23.  
  24. The Apple IIGS Installer, a utility program that is included with Apple IIGS 
  25. System Software, can be used to install System Software or applications on a 
  26. given volume.  "Scripts" control the Installer, and they are simply lists of 
  27. files with information about where and how to install those files.  The user 
  28. interface of the Installer is described in the Apple IIGS System Tools Manual.  
  29. This Note describes how the Installer executes scripts and how to write 
  30. scripts to install your applications.
  31.  
  32.  
  33. Installer Setup on Disk
  34.  
  35. Setting up the Installer on your application disk is a simple procedure.
  36.  
  37.   1.  Copy the Installer program to your application disk.
  38.   2.  Create a subdirectory (folder) named Scripts at the same directory 
  39.       level as the Installer program.
  40.   3.  Copy your scripts into the Scripts subdirectory.
  41.  
  42.  
  43. How the Installer Processes Scripts
  44.  
  45. The Installer reads script files into memory in their entirety, parses them, 
  46. strips them of all comments, compacts them, then verifies them.  It then 
  47. checks the scriptFlags field to see if a Caution alert should be displayed.  
  48. This facility permits the script writer to force the user to read the script's 
  49. help message and make a choice to either continue with file manipulations or 
  50. skip the installation altogether, which is especially useful when a script 
  51. installation would be inappropriate on a certain volume.
  52.  
  53. The Installer then executes the script in two passes.  The first pass 
  54. determines if the update can be completed by calculating the total size of the 
  55. files to be deleted from the destination volume and of the files to be 
  56. installed.  If there is not sufficient room on the destination volume, the 
  57. Installer determines the amount of additional space required to complete 
  58. installation (number of blocks needed divided by two, plus one), reports this 
  59. result to the user in terms of kilobytes, then terminates execution of the 
  60. script.  It is impossible to determine directory block requirements with 
  61. complete accuracy.  The Installer's space calculation algorithms are good, but 
  62. they are not perfect.
  63.  
  64. If the first pass determines that there is sufficient room for the complete 
  65. update, the Installer continues with the second pass, deleting and copying 
  66. files in accordance with the instructions contained in the script flags.  The 
  67. Installer "blindly" unlocks locked files and folders, creates necessary 
  68. subdirectories if they do not already exist, and replaces requested files 
  69. without regard to version numbers or creation dates of existing files.
  70.  
  71. The user may terminate execution of any script (and of those which follow) by 
  72. pressing the Open Apple-Period key combination.  The Installer checks 
  73. for key-down events between every file transfer and at the end of the first 
  74. pass.  If the user requests termination, the Installer warns of the 
  75. possibility of leaving an unknown mix of file versions on the volume and gives 
  76. the user the opportunity to continue with the installation or to terminate as 
  77. requested.  (See the "Error Handling" section for more details.)
  78.  
  79. Scripts are typically written with the ability to remove all of their related 
  80. files from a particular volume (i.e., in case of an accidental installation); 
  81. however, they do not have the ability to remove directories which contain 
  82. files (even if the script installed them), and they can neither recover nor 
  83. list files which were deleted during the installation process.
  84.  
  85. After processing all the instructions in a script, the Installer checks to see 
  86. if additional scripts are selected, and, if they are, it executes them in the 
  87. order in which they appear in the update selection window until all scripts 
  88. are successfully completed.  Once all selected scripts are completed, the 
  89. Installer notifies the user that the installation or removal process was 
  90. successful.
  91.  
  92. It is important to note several facts about script execution:
  93.  
  94.   o  Each script is processed from beginning to end as if it were the 
  95.      only script selected.
  96.   o  If the execution of a script generates an error, or if the user 
  97.      terminates further processing of a script, the queue is cleared of 
  98.      any additional scripts waiting to be executed and control returns 
  99.      to the user.
  100.   o  It is possible for the Installer to execute several scripts 
  101.      successfully before encountering one which cannot be executed due 
  102.      to insufficient space on the destination volume.
  103.   o  All selected scripts use the folder that the user selects as the 
  104.      "Application Folder."
  105.  
  106. If a user installs or removes system files (i.e., tools, fonts, drivers, etc.) 
  107. from the boot volume, it may create problems.  Therefore, whenever a system 
  108. level update occurs on a boot volume, the Installer disables all desk 
  109. accessories and closes the Sys.Resources file.  When the user quits the 
  110. Installer after a system level update, it alerts the user of the need to 
  111. restart the system, and the default response to this alert is to restart.
  112.  
  113.  
  114. Error Handling
  115.  
  116. User Cancel Request
  117.  
  118. If the user cancels script execution any time after it has started (i.e., by 
  119. pressing the Open-Apple-Period key combination), the Installer treats 
  120. it as an error condition since there is likely an unknown mix of file versions 
  121. on the volume.  In this case, the Installer gives the user the opportunity to 
  122. continue with the installation or to terminate as requested.  A user-initiated 
  123. cancel request is not acknowledged until the current file copy or delete 
  124. request is complete.  Terminating script execution also clears the queue of 
  125. other scripts waiting for execution and returns control to the user.
  126.  
  127. Non-Recoverable Errors
  128.  
  129. Some errors are simply fatal.  If a directory or file is corrupted, the media 
  130. is bad, or the selected script is longer than 65,535 bytes, the Installer 
  131. halts execution of the script and alerts the user that a fatal error has 
  132. occurred with a Stop alert box.  Clicking the OK button in this alert box 
  133. clears the queue of other scripts waiting for execution and returns control to 
  134. the user.
  135.  
  136. Script Errors and File Not Found Errors
  137.  
  138. When the Installer detects a script error or a File Not Found error, it 
  139. reports the name of the source file and destination file it was processing 
  140. with the normal error message.  This additional information should help script 
  141. writers find the offending fileSpecification field.  If the error is 
  142. associated with the header, no filename is reported.  This condition clears 
  143. the queue of other scripts waiting for execution and returns control to the 
  144. user.
  145.  
  146. Volume Not Found Errors
  147.  
  148. Volume Not Found errors produce a dialog box prompting the user to insert the 
  149. missing volume.  If the user clicks the OK button, the Installer attempts the 
  150. file access call again, but if the user clicks the Cancel button, the 
  151. Installer flags it as an error condition, clears the queue of other scripts 
  152. waiting for execution, and returns control to the user.
  153.  
  154.  
  155. Script File Composition
  156.  
  157. A script is simply a list of instructions for the Installer, and it can 
  158. specify that files be copied from a source volume to a destination volume (or 
  159. directory, when applicable) or that files be removed from a destination 
  160. volume.  Script files are ASCII files (file type $04) containing printable 
  161. ASCII characters (i.e., with the high-bit clear).  The directory in which the 
  162. Installer resides must contain a directory named Scripts, in which all script 
  163. files visible to that copy of the Installer must be located.  Script files may 
  164. not exceed 65,535 bytes in length.  Any attempt to execute a script larger 
  165. than this size produces a non-recoverable error.
  166.  
  167. A script consists of a header field followed by any number of 
  168. fileSpecification and comment fields.  These fields are separated by tildes 
  169. (~).  Two consecutive tildes signal the end of the script, and any additional 
  170. characters past the end of script marker are ignored.  Figure 1 shows the 
  171. syntax diagram for a script.
  172.  
  173.       ________                                                 ____
  174.   __>| header |______________________________________________>( ~~ )__>
  175.      |________|  \     ___      ___________________       /   (____)
  176.                   \__>( ~ )___>| fileSpecification |_     |
  177.                   /   (___) \  |___________________| \    |
  178.                   |         |    _________           |    |
  179.                   |         \__>| comment |__________\____/
  180.                   |             |_________|             \
  181.                   \_____________________________________/
  182.  
  183.                       Figure 1-Script Syntax Diagram
  184.  
  185. header Field
  186.  
  187. The header field consists of the scriptIdentifier, scriptVersion, scriptFlag, 
  188. scriptName, and scriptHelp fields, and it may also contain an optional 
  189. sourcePrefix field.  These fields supply the installer with general 
  190. information about the script file.  No comments are permitted within the 
  191. header field.  Figure 2 shows the syntax diagram for the header field.
  192.  
  193.                           __________________
  194.                      ___>| scriptIdentifier |__
  195.                          |__________________|  \
  196.                       _________________________/
  197.                      /    __________________
  198.                      \__>| scriptVersion    |__
  199.                          |__________________|  \
  200.                       _________________________/
  201.                      /    __________________
  202.                      \__>| scriptFlag       |__
  203.                          |__________________|  \
  204.                       _________________________/
  205.                      /    __________________
  206.                      \__>| scriptName       |__
  207.                          |__________________|  \
  208.                       _________________________/
  209.                      /    __________________
  210.                      \__>| scriptHelp       |________>
  211.                          |__________________|  \  /
  212.                       _________________________/  |
  213.                      /    __________________      |
  214.                      \__>| sourcePrefix     |_____/
  215.                          |__________________|
  216.  
  217.                   Figure 2-header Field Syntax Diagram
  218.  
  219. The scriptIdentifier field identifies the text file as a script file, and it 
  220. consists of eight characters ("SCRIPT" followed by two carriage returns, or 53 
  221. 43 52 49 50 54 0D 0D in hexadecimal).  Figure 3 shows the syntax diagram for 
  222. the scriptIdentifier field.
  223.  
  224.             ___________________________________________________
  225.         __>( "SCRIPT" followed by 2 carriage return characters )__>
  226.            (___________________________________________________)
  227.  
  228.                Figure 3-scriptIdentifier Field Syntax Diagram
  229.  
  230. The scriptVersion field defines the minimum version of the Installer program 
  231. that can read and execute the instructions in this script file.  It should 
  232. normally consist of seven characters ("V1.10" followed by two carriage 
  233. returns, or 56 31 2E 31 30 0D 0D in hexadecimal).
  234.  
  235. Version 1.0 of the Installer moves only the data fork and does not return an 
  236. error.  For compatibility with the original release of the Installer, the 
  237. value of scriptVersion is V1.00.  Scripts which move extended files (i.e., 
  238. files with resource forks) or work with an AppleShare volume must have a 
  239. scriptVersion of V1.10.  Figure 4 shows the syntax diagram for the 
  240. scriptVersion field.
  241.  
  242.             __________________________________________________
  243.         __>( "V1.10" followed by 2 carriage return characters )__>
  244.            (__________________________________________________)
  245.  
  246.                 Figure 4-scriptVersion Field Syntax Diagram
  247.  
  248. The scriptFlag field defines the directory requirements of the script file.  
  249. The first character of the scriptFlag field must be either the uppercase 
  250. character "R" (indicating that the installation must occur at the root 
  251. directory, such as in a System Software update) or the uppercase character "X" 
  252. (indicating that the user must specify the directory where installation should 
  253. take place).
  254.  
  255. The second character of the scriptFlag field must be either an uppercase or 
  256. lowercase character "R" (indicating that the Remove command is valid for this 
  257. script) or an uppercase or lowercase character "N" (indicating that the Remove 
  258. command is not valid and the button should be dimmed and inactive).  If this 
  259. character is lowercase, before any file manipulations begin, the Installer 
  260. displays a Caution alert with the contents of the scriptHelp field and button 
  261. controls to permit the user to choose whether to execute the script or to skip 
  262. it and go to the next script, if any.
  263.  
  264. For example, a scriptFlag field might  contain the following four characters:  
  265. "Rr" followed by two carriage returns, or 52 52 0D 0D in hexadecimal.  Figure 
  266. 5 shows the syntax diagram for the scriptFlag field.
  267.  
  268.            ___            ___         ______________________________
  269.     _____>( R )_________>( R )______>( 2 carriage return characters )__>
  270.       \   (___)  /  \    (___)   /   (______________________________)
  271.       |    ___   |  |     ___    |
  272.       \__>( X )__/  |\__>( r )__/|
  273.           (___)     |    (___)   |
  274.                     |     ___    |
  275.                     |\__>( N )__/|
  276.                     |    (___)   |
  277.                     |     ___    |
  278.                     \___>( n )___/
  279.                          (___)
  280.  
  281.                 Figure 5-scriptFlag Field Syntax Diagram
  282.  
  283. The scriptName field defines the name of the script as it appears in the 
  284. Installer's script selection window.  It is recommended that care be taken to 
  285. use a name that fits within the display window.  This field consists of any 
  286. number of characters ending with a carriage return and may not include a tilde 
  287. or carriage return.  An example of scriptName might be: "Example Script" 
  288. followed by a carriage return, or 45 78 61 6D 70 6C 65 20 53 63 72 69 70 74 0D 
  289. in hexadecimal.  Figure 6 shows the syntax diagram for the scriptName field.
  290.  
  291.               ____________________________________________
  292.     ________>( any character except ~ and carriage return )_____
  293.       \  /   (____________________________________________)  \  \
  294.       |  \___________________________________________________/  |
  295.       | ________________________________________________________/
  296.       |/
  297.       |                                        _________________
  298.       \______________________________________>( carriage return )__>
  299.                                               (_________________)
  300.  
  301.                Figure 6-scriptName Field Syntax Diagram
  302.  
  303. The scriptHelp field defines the text which appears when the user clicks the 
  304. Help button.  It is recommended that care be taken to ensure the text fits 
  305. within the help window.  This field consists of any number of characters 
  306. ending with two backslashes (\\) and a carriage return.  It may not include 
  307. two consecutive backslashes or a tilde; however, it may include carriage 
  308. returns.  An example of scriptHelp might be: "Help\\" followed by a carriage 
  309. return, or 48 65 6C 70 5C 5C 0D in hexadecimal.  Figure 7 shows the syntax 
  310. diagram for the scriptHelp field.
  311.  
  312.                       _______________________________
  313.             ________>( any character except \\ and ~ )_____
  314.               \  /   (_______________________________)  \  \
  315.               |  \______________________________________/  |
  316.               | ___________________________________________/
  317.               |/
  318.               |          __________________________________
  319.               \________>( \\ followed by a carriage return )__>
  320.                         (__________________________________)
  321.  
  322.                  Figure 7-scriptHelp Field Syntax Diagram
  323.  
  324. The optional sourcePrefix field is the prefix used with source files defined 
  325. by partial pathnames.  Either slashes (/) or colons (:) may be used as the 
  326. pathname separator character.  If there is no sourcePrefix, this entry must be 
  327. empty.  If no sourcePrefix is specified, all sourcePathname fields used within 
  328. fileSpecification fields must be full pathnames.  An example of a sourcePrefix 
  329. might be: ":System.Disk:System", or 3A 53 79 73 74 65 6D 2E 44 69 73 6B 3A 53 
  330. 79 73 74 65 6D in hexadecimal.  Figure 8 shows the syntax diagram for the 
  331. sourcePrefix field.  GS/OS Reference defines legal pathnames and prefixes.
  332.  
  333.                         ____________________
  334.                     __>( legal GS/OS prefix )__>
  335.                        (____________________)
  336.  
  337.              Figure 8-sourcePrefix Field Syntax Diagram
  338.  
  339. fileSpecification Field
  340.  
  341. A fileSpecification field contains the instructions to copy a file to or 
  342. remove a file from the destination volume (or directory, when applicable).  A 
  343. fileSpecification field is composed of the fileSpecWorkspace, fileSpecFlags, 
  344. fileTypeAuxType, createDateTime, sourcePathname, and destinationPathname 
  345. fields.  The script may contain as many fileSpecification fields as necessary.  
  346. Figure 9 shows the syntax diagram for the fileSpecification field.
  347.  
  348.                           _____________________
  349.                      ___>| fileSpecWorkspace   |__
  350.                          |_____________________|  \
  351.                       ____________________________/
  352.                      /    _____________________
  353.                      \__>| fileSpecFlags       |__
  354.                          |_____________________|  \
  355.                       ____________________________/
  356.                      /    _____________________
  357.                      \__>| fileTypeAuxType     |__
  358.                          |_____________________|  \
  359.                       ____________________________/
  360.                      /    _____________________
  361.                      \__>| createDateTime      |__
  362.                          |_____________________|  \
  363.                       ____________________________/
  364.                      /    _____________________
  365.                      \__>| sourcePathname      |________>
  366.                          |_____________________|  \  /
  367.                       ____________________________/  |
  368.                      /    _____________________      |
  369.                      \__>| destinationPathname |_____/
  370.                          |_____________________|
  371.  
  372.               Figure 9-fileSpecification Field Syntax Diagram
  373.  
  374. The fileSpecWorkspace field is 16 bytes that the Installer uses for work 
  375. space, it can contain any character except a tilde, and it may not begin with 
  376. a tilde or an asterisk (*).  It is suggested that 15 readable characters 
  377. followed by a carriage return might be easiest to see and count.  An example 
  378. of fileSpecWorkspace might be: ":::Workspace:::" followed by a carriage 
  379. return, or 3A 3A 3A 57 6F 72 6B 73 70 61 63 65 3A 3A 3A 0D in hexadecimal.  
  380. Figure 10 shows the syntax diagram for the fileSpecWorkspace field.
  381.  
  382.                 ________________________________ 
  383.             __>( any 1 character except ~ and * )__
  384.                (________________________________)  \
  385.                    ________________________________/
  386.                   /    ____________________________
  387.                   \__>( any 15 characters except ~ )__>
  388.                       (____________________________)
  389.  
  390.             Figure 10-fileSpecWorkspace Field Syntax Diagram
  391.  
  392. The fileSpecFlags tell the Installer what this fileSpecification does.  The 
  393. fileSpecFlags field consists of the requiredFlag field followed by the 
  394. optionalFlags field and a carriage return.  Figure 11 shows the syntax diagram 
  395. for the fileSpecFlags field.
  396.  
  397.         ______________     _______________     _________________
  398.     __>| requiredFlag |__>| optionalFlags |__>( carriage return )__>
  399.        |______________|   |_______________|   (_________________)
  400.  
  401.               Figure 11-fileSpecFlags Field Syntax Diagram
  402.  
  403. The requiredFlag field tells the Installer what to do with this 
  404. fileSpecification when the Install or Remove buttons are used.  The 
  405. requiredFlag field must start with only one of the following characters:  1, 
  406. 2, 3, or 4, and it must end with a carriage return.  Any number of characters 
  407. (except tilde and carriage return ) may fall between the flag character and 
  408. the ending carriage return.  These additional characters are ignored by the 
  409. Installer, making it possible to place comments within a requiredFlag field.  
  410. Figure 12 shows the syntax diagram for the requiredFlag field.
  411.  
  412. The four requiredFlag characters tell the installer the following:
  413.  
  414.   1  If the user clicks the Install button, delete the 
  415.      destinationPathname from the destination volume, if it exists, and 
  416.      copy the file from the source volume.  If the user clicks the 
  417.      Remove button, delete the destinationPathname from the destination 
  418.      volume, if it exists.
  419.   2  If the user clicks the Install button, delete the 
  420.      destinationPathname from the destination volume, if it exists, and 
  421.      copy the file from the source volume.  If the user clicks the 
  422.      Remove button, do nothing.
  423.   3  If the user clicks the Install button, delete the 
  424.      destinationPathname from the destination volume, if it exists.  If 
  425.      the user clicks the Remove button, delete the destinationPathname 
  426.      from the destination volume, if it exists.
  427.   4  If the user clicks the Install button, delete the 
  428.      destinationPathname from the destination volume, if it exists.  If 
  429.      the user clicks the Remove button, do nothing.
  430.  
  431.             ___     
  432.     ______>( 1 )______
  433.       \    (___)   /  \
  434.       |     ___    |  |
  435.       |\__>( 2 )__/|  |
  436.       |    (___)   |  |
  437.       |     ___    |  |
  438.       |\__>( 3 )__/|  |
  439.       |    (___)   |  |
  440.       |     ___    |  |
  441.       \___>( 4 )___/  |
  442.            (___)      |
  443.       _______________/|
  444.      /                |
  445.      |                \______________________________________
  446.      |    ____________________________________________       \
  447.      \__>( any character except ~ and carriage return )_____ |
  448.      /   (____________________________________________)  \  \|
  449.      \___________________________________________________/   |
  450.                                         _____________________/
  451.                                        /    _________________
  452.                                        \__>( carriage return )__>
  453.                                            (_________________)
  454.  
  455.                 Figure 12-requiredFlag Field Syntax Diagram
  456.  
  457. The optionalFlags field gives the Installer additional duties to perform with 
  458. this fileSpecification when the Install or Remove buttons are used.  The five 
  459. option fields, B, C, D, F, and U (must be uppercase), within the optionalFlags 
  460. field are formatted the same as the requiredFlag field.  Figure 13 shows the 
  461. syntax diagram for the optionalFlags field.
  462.  
  463. The five optionalFlags characters tell the installer the following:
  464.  
  465.   B  This flag instructs the Installer to replace the boot code on 
  466.      blocks zero and one of the destination volume.  The boot code 
  467.      replacement fileSpecification is reserved for use by Apple 
  468.      Computer, Inc.
  469.   C  The creation date and time of the file designated by the 
  470.      sourcePathname field must match the createDateTime entry in this 
  471.      fileSpecification field.
  472.   D  The designated destinationPathname should be deleted if, and only 
  473.      if, it  has a creation date and time that is older than 
  474.      createDateTime.  This flag must be used with a "4" requiredFlag.
  475.   F  The file type and auxiliary type of the file designated by the 
  476.      sourcePathname must match the fileTypeAuxType field in this 
  477.      fileSpecification field.
  478.   U  Update (replace) the existing destinationPathname only if it 
  479.      exists.  This flag must be used with a "1" or a "2" requiredFlag.
  480.  
  481.         ___     
  482. ______>( B )__________________________________________________________
  483.   \    (___) \     ____________________________________________    /  \
  484.   |           \__>( any character except ~ and carriage return )__/   |
  485.   |           /   (____________________________________________)  \   |
  486.   |           \___________________________________________________/   |
  487.   |                                        ___________________________/
  488.   |                                       /    _________________
  489.   |                                       \__>( carriage return )_________
  490.   |     ___                                   (_________________)         \
  491.   |\__>( C )___________________________________________________________   |
  492.   |    (___)  \     ____________________________________________    /  \  |
  493.   |            \__>( any character except ~ and carriage return )__/   |  |
  494.   |            /   (____________________________________________)  \   |  |
  495.   |            \___________________________________________________/   |  |
  496.   |                               _________________                    |  |
  497.   | _____________________________( carriage return )<__________________/  |
  498.   |/    ___                      (_________________)                      |
  499.   |\__>( D )___________________________________________________________   |
  500.   |    (___)  \     ____________________________________________    /  \  |
  501.   |            \__>( any character except ~ and carriage return )__/   |  |
  502.   |            /   (____________________________________________)  \   |  |
  503.   |            \___________________________________________________/   |  |
  504.   |                               _________________                    |  |
  505.   | _____________________________( carriage return )<__________________/  |
  506.   |/    ___                      (_________________)                      |
  507.   |\__>( F )___________________________________________________________   |
  508.   |    (___)  \     ____________________________________________    /  \  |
  509.   |            \__>( any character except ~ and carriage return )__/   |  |
  510.   |            /   (____________________________________________)  \   |  |
  511.   |            \___________________________________________________/   |  |
  512.   |                               _________________                    |  |
  513.   | _____________________________( carriage return )<__________________/  |
  514.   |/    ___                      (_________________)                      |
  515.   |\__>( U )___________________________________________________________   |
  516.   |    (___)  \     ____________________________________________    /  \  |
  517.   |            \__>( any character except ~ and carriage return )__/   |  |
  518.   |            /   (____________________________________________)  \   |  |
  519.   |            \___________________________________________________/   |  |
  520.   |                               _________________                    |  |
  521.   | _____________________________( carriage return )<__________________/  |
  522.   |/                             (_________________)                      |
  523.   |                                                                       |
  524.   \_______________________________________________________________________\__>
  525.  
  526.               Figure 13-optionalFlags Field Syntax Diagram
  527.  
  528. The fileTypeAuxType field is used if the "F" optionalFlags field is present in 
  529. the fileSpecification field.  If the fileTypeAuxType field is used, it must 
  530. start with a fileType field and an auxType field and must end with a carriage 
  531. return.  Any number of characters (except tilde and carriage return) may fall 
  532. between the auxType field and the ending carriage return.  These additional 
  533. characters are ignored by the Installer, making it possible to place comments 
  534. within the fileTypeAuxType field.  If the "F" optionalFlags field is not used, 
  535. then the fileTypeAuxType field must be only a carriage return.  For a list of 
  536. current file types and auxiliary types, see the Apple II File Type Notes.  
  537. Figure 14 shows the syntax diagram for the fileTypeAuxType field.
  538.  
  539.                                                    _________________
  540.     _____________________________________________>( carriage return )__>
  541.       \     __________     _________          /   (_________________)
  542.        \__>| fileType |__>| auxType |________/
  543.            |__________|   |_________|  \  /
  544.                ________________________/  \_______________________
  545.               /    ____________________________________________   \
  546.               \__>( any character except ~ and carriage return )__/
  547.               /   (____________________________________________)  \
  548.               \___________________________________________________/
  549.  
  550.               Figure 14-fileTypeAuxType Field Syntax Diagram
  551.  
  552. The fileType part of the fileTypeAuxType field consists of four, and only 
  553. four, hexadecimal digits.  These four digits identify a GS/OS file type if the 
  554. "F" optionalFlags field is present in the fileSpecification field.  An example 
  555. of fileType might be: "00B3", or 30 30 42 33 in hexadecimal.  Figure 15 shows 
  556. the syntax diagram for the fileType field.
  557.  
  558.                     _______________________________________
  559.                 __>( four and only four hexadecimal digits )__>
  560.                    (_______________________________________)
  561.  
  562.                     Figure 15-fileType Field Syntax Diagram
  563.  
  564. The auxType part of the fileTypeAuxType field consists of eight, and only 
  565. eight, hexadecimal digits.  These eight hexadecimal digits identify a GS/OS 
  566. auxiliary type if the "F" optionalFlags field is present in the 
  567. fileSpecification field.  An example of auxType might be: "00000000", or 30 30 
  568. 30 30 30 30 30 30 in hexadecimal.  Figure 16 shows the syntax diagram for the 
  569. auxType field.
  570.  
  571.                     _________________________________________
  572.                 __>( eight and only eight hexadecimal digits )__>
  573.                    (_________________________________________)
  574.  
  575.                       Figure 16-auxType Field Syntax Diagram
  576.  
  577. The createDateTime field is used if the "C" or "D" optionalFlags fields are 
  578. present in the fileSpecification field.  If the createDateTime field is used, 
  579. it must start with a date field, a single space and a time field and must end 
  580. with a carriage return.  Any number of characters (except tilde and carriage 
  581. return) may fall between the time field and the ending carriage return.  These 
  582. additional characters are ignored by the Installer, making it possible to 
  583. place comments within the createDateTime field.  If the "C" or "D" 
  584. optionalFlags fields are not used, then the createDateTime field must be only 
  585. a carriage return.  Figure 17 shows the syntax diagram for the createDateTime 
  586. field.
  587.  
  588.                                                     _________________
  589.     ______________________________________________>( carriage return )__>
  590.       \     ______     _______     ______      /   (_________________)
  591.        \__>| date |__>( space )__>| time |__   |
  592.            |______|   (_______)   |______|  \  |
  593.                _____________________________/  \__________________
  594.               /    ____________________________________________   \
  595.               \__>( any character except ~ and carriage return )__/
  596.               /   (____________________________________________)  \
  597.               \___________________________________________________/
  598.  
  599.                Figure 17-createDateTime Field Syntax Diagram
  600.  
  601. The date subfield of the createDateTime field is nine ASCII characters 
  602. consisting of the day of the month, a space, a three-character month 
  603. abbreviation, a space, and the year.  The day of the month is a two-character 
  604. number between 01 and 31.  The month abbreviation may be "Jan", "Feb", "Mar", 
  605. "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", or "Dec" in any 
  606. combination of uppercase and lowercase characters.  The year is a two-
  607. character number between 00 and 99.  An example of the date subfield might be: 
  608. "31 Mar 57", or 33 31 20 4D 61 72 20 35 37 in hexadecimal.  Figure 18 shows 
  609. the syntax diagram for the date subfield.
  610.  
  611.             _________________________________     _______
  612.         __>( two and only two decimal digits )__>( space )__
  613.            (_________________________________)   (_______)  \
  614.            _________________________________________________/
  615.           /    ____________________________________     _______
  616.           \__>( three character month abbreviation )__>( space )__
  617.               (____________________________________)   (_______)  \
  618.            _______________________________________________________/
  619.           /    _________________________________
  620.           \__>( two and only two decimal digits )__>
  621.               (_________________________________)
  622.  
  623.                    Figure 18-date Field Syntax Diagram
  624.  
  625. The time subfield of the createDateTime field is five ASCII characters 
  626. consisting of the military format hour of the day, a colon, and the minute of 
  627. the hour.  The hour of the day is a two-character number between 00 and 23.  
  628. The minute of the hour is a two-character number between 00 and 59.  An 
  629. example of the time subfield might be: "08:30", or 30 38 3A 33 30 in 
  630. hexadecimal.  Figure 19 shows the syntax diagram for the time subfield.
  631.  
  632.             _________________________________
  633.         __>( two and only two decimal digits )__
  634.            (_________________________________)  \
  635.            _____________________________________/
  636.           /    _______     _________________________________
  637.           \__>( colon )__>( two and only two decimal digits )__>
  638.               (_______)   (_________________________________)
  639.  
  640.                     Figure 19-time Field Syntax Diagram
  641.  
  642. The sourcePathname field describes the name and location of the source file.  
  643. The sourcePathname field consists of a valid GS/OS pathname followed by a 
  644. carriage return.  If the sourcePathname is a partial pathname, the 
  645. sourcePrefix in the header field is used to complete the full pathname.  If no 
  646. sourcePrefix is specified in the header field, all sourcePathname fields must 
  647. be full pathnames.  If the fileSpecFlags indicate removal only, then the 
  648. sourcePathname is a carriage return only.  No optional comments are permitted 
  649. in this field.  Figure 20 shows the syntax diagram for the sourcePathname 
  650. field.  GS/OS Reference defines legal pathnames and prefixes.
  651.                                            _________________
  652.     _____________________________________>( carriage return )__>
  653.       \     ______________________    /   (_________________)
  654.        \__>( valid GS/OS pathname )__/
  655.            (______________________)
  656.  
  657.              Figure 20-sourcePathname Field Syntax Diagram
  658.  
  659. The destinationPathname field describes the name and location of the 
  660. destination file.  The destinationPathname field consists of a valid GS/OS 
  661. partial pathname (the prefix has already been set by the Installer to the 
  662. location of the destination directory, either the root directory or a user 
  663. selected directory) followed by a carriage return.  No optional comments are 
  664. permitted in this field.  Figure 21 shows the syntax diagram for the 
  665. destinationPathname field.  GS/OS Reference defines legal pathnames and 
  666. prefixes.
  667.  
  668. Note that GS/OS now allows filenames to contain both uppercase and lowercase 
  669. characters.  Although filenames are not case sensitive, you should be 
  670. consistent in your use of uppercase and lowercase usage in the 
  671. destinationPathname field.  Whatever you use here is what everyone sees.
  672.  
  673.         ______________________________     _________________
  674.     __>( valid GS/OS partial pathname )__>( carriage return )__>
  675.        (______________________________)   (_________________)
  676.  
  677.           Figure 21-destinationPathname Field Syntax Diagram
  678.  
  679. comment Field
  680.  
  681. The comment field allows commenting script files.  A comment field must begin 
  682. with an asterisk.  The Installer ignores all characters within a comment 
  683. field, except tilde, and the comment field ends at the first tilde 
  684. encountered.  Figure 22 shows the syntax diagram for the comment field.
  685.  
  686.                 ___
  687.             __>( * )_______________________________________>
  688.                (___)  \     ________________________    /
  689.                        \__>( any character except ~ )__/
  690.                        /   (________________________)  \
  691.                        \_______________________________/
  692.  
  693.                   Figure 22-comment Field Syntax Diagram
  694.  
  695.  
  696. Examples
  697.  
  698. Now that the script language is described, it's time to look at a couple of 
  699. example scripts.  The first example, CD-ROM from the System.Tools disk, 
  700. installs the files necessary for you to use CD-ROM drives.  The CD-ROM script 
  701. is an example of using the Installer to install or update existing software.  
  702. The second example, Advanced Disk Utility from the System.Tools disk, installs 
  703. the files necessary to update the Advanced Disk Utility program.  The Advanced 
  704. Disk Utility script is an example of using the Installer to install an 
  705. application in any directory on the destination volume.  In both examples 
  706. (Examples 1 and 2), carriage returns are shown with a paragraph mark ([p]) since 
  707. they are used as delimiters within scripts.
  708.  
  709. The CD-ROM Script
  710.  
  711. The header field starts with "SCRIPT" to identify this text file as a script 
  712. file.  The scriptVersion is "V1.10" because this script may have to copy the 
  713. resource fork of a file.  The scriptFlag field is "RR", which tells the 
  714. Installer to install at the root directory level and that the Remove button is 
  715. valid for this script.  The second "R" character in the scriptFlag field is 
  716. uppercase, which tells the Installer not to display a Caution alert with the 
  717. contents of the scriptHelp field.  The scriptName field is "CD-ROM".  The 
  718. scriptName is shown in the Installer's list of scripts.  The scriptHelp field 
  719. (everything between the scriptName field and the "\\" delimiter) is the text 
  720. that will be displayed if the Installer's Help button is used.  The 
  721. sourcePrefix is ":SYSTEM.TOOLS".  That is the name of the volume where the 
  722. source files for this update are found.
  723.  
  724. After the header field, there is a single comment field and then five 
  725. fileSpecification fields.  The comment field starts at the asterisk after the 
  726. first tilde and ends at the next tilde.  All five fileSpecification fields 
  727. start with the suggested 16-byte fileSpecWorkSpace (":::WorkSpace:::[p]") and 
  728. end at the next tilde.
  729.  
  730. The first, fourth, and fifth fileSpecification fields use the "1" 
  731. requiredFlag.  This flag tells the Installer to copy the sourcePathname to the 
  732. destinationPathname if the Install button is used, or to delete the 
  733. destinationPathname if the Remove button is used.  Notice the three blank 
  734. lines after the "1" requiredFlag.  The first blank line marks the end of the 
  735. fileSpecFlags.  The fileTypeAuxType field, the second blank line, is blank 
  736. because the "F" optionalFlags field is not used.  The createDateTime field, 
  737. the third blank line, is blank because the "C" and "D" optionalFlags are not 
  738. used.
  739.  
  740. The second fileSpecification field uses the "3" requiredFlag to tell the 
  741. Installer to delete the destinationPathname, "System:Drivers:SCSI.Driver", if 
  742. either the Install or the Delete button is used.  SCSI.Driver is the interim 
  743. SCSI driver from System Software 4.0.  The sourcePathname field, the fourth 
  744. blank line after the "3" requiredFlag, is not needed since the "3" 
  745. requiredFlag is used.
  746.  
  747. The third fileSpecification field uses the "2" requiredFlag to tell the 
  748. Installer to delete the destinationPathname, "System:Drivers:SCSI.Manager" if 
  749. the Install button is used.  The Installer does not delete the 
  750. destinationPathname if the Remove button is used.  The "2" requiredFlag 
  751. prevents this script from removing SCSI.Manager, which might have been 
  752. installed by another script.
  753.  
  754. Two consecutive tildes after the fifth fileSpecification field signal the end 
  755. of this script.
  756.  
  757.  
  758. SCRIPT[p]
  759. [p]
  760. V1.10[p]
  761. [p]
  762. RR[p]
  763. [p]
  764. CD-ROM[p]
  765. This script installs the files necessary for you to use CD-ROM drives.  The 
  766. selected disk must be a startup disk.\\[p]
  767. :SYSTEM.TOOLS~*[p]
  768.  This is the Installer script necessary to move the CD-ROM files from 
  769. :SYSTEM.TOOLS to the user's startup disk.[p]
  770. ~:::Workspace:::[p]
  771. 1[p]
  772. [p]
  773. [p]
  774. [p]
  775. System:FSTs:HS.FST[p]
  776. System:FSTs:HS.FST[p]
  777. ~:::Workspace:::[p]
  778. 3[p]
  779. [p]
  780. [p]
  781. [p]
  782. [p]
  783. System:Drivers:SCSI.Driver[p]
  784. ~:::Workspace:::[p]
  785. 2[p]
  786. [p]
  787. [p]
  788. [p]
  789. System:Drivers:SCSI.Manager[p]
  790. System:Drivers:SCSI.Manager[p]
  791. ~:::Workspace:::[p]
  792. 1[p]
  793. [p]
  794. [p]
  795. [p]
  796. System:Drivers:SCSICD.Driver[p]
  797. System:Drivers:SCSICD.Driver[p]
  798. ~:::Workspace:::[p]
  799. 1[p]
  800. [p]
  801. [p]
  802. [p]
  803. System:Desk.Accs:CDRemote[p]
  804. System:Desk.Accs:CDRemote[p]
  805. ~~
  806.  
  807.                          Example 1-CD-ROM Script
  808.  
  809.  
  810. The Advanced Disk Utility Script
  811.  
  812. The header field starts with "SCRIPT" to identify this text file as a script 
  813. file.  The scriptVersion is "V1.10" because this script may have to copy the 
  814. resource fork of a file.  The scriptFlag field is "XR", which tells the 
  815. Installer the user must specify the directory where the installation should 
  816. take place and that the Remove button is valid for this script.  The second 
  817. character (R) in the scriptFlag field is uppercase, which tells the Installer 
  818. not to display a Caution alert with the contents of the scriptHelp field.  
  819. The scriptName field is "Advanced Disk Utility".  The scriptName will be shown 
  820. in the Installer's list of scripts.  The scriptHelp field (everything between 
  821. the scriptName field and the "\\" delimiter) is the text that will be 
  822. displayed if the Installer's Help button is used.  The sourcePrefix is 
  823. ":SYSTEM.TOOLS".  That is the name of the volume where the source files for 
  824. this update are found.
  825.  
  826. After the header field, there is a single comment field then one 
  827. fileSpecification field. The comment field starts at the asterisk after the 
  828. first tilde and ends at the next tilde.  The fileSpecification field starts 
  829. with the suggested 16-byte fileSpecWorkSpace (":::WorkSpace:::[p]") and ends at 
  830. the next tilde.
  831.  
  832. The fileSpecification field uses the "1" requiredFlag.  This tells the 
  833. Installer to copy the sourcePathname to the destinationPathname if the Install 
  834. button is used or to delete the destinationPathname if the Remove button is 
  835. used.
  836.  
  837. Two consecutive tildes signal the end of this script.
  838.  
  839. SCRIPT[p]
  840. [p]
  841. V1.10[p]
  842. [p]
  843. XR[p]
  844. [p]
  845. Advanced Disk Utility[p]
  846. This script installs the files necessary to update the Advanced Disk Utility 
  847. program.  These files will be installed on the selected disk.\\[p]
  848. :SYSTEM.TOOLS~*[p]
  849.  This is the Installer script necessary to update the Advanced Disk Utility 
  850. file from :SYSTEM.TOOLS to the user's disk.[p]
  851. ~:::Workspace:::[p]
  852. 1[p]
  853. [p]
  854. [p]
  855. [p]
  856. Adv.Disk.Util[p]
  857. Adv.Disk.Util[p]
  858. ~~
  859.  
  860.                    Example 2-Advanced Disk Utility Script
  861.  
  862.  
  863. Further Reference
  864. _____________________________________________________________________________
  865.   o  Apple IIGS System Tools  Manual
  866.   o  GS/OS Reference